Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Installing and Configuring Your ROS Environment

Description: This tutorial walks you through installing ROS and setting up the ROS environment on your computer.

Tutorial Level: BEGINNER

Next Tutorial: Navigating the ROS Filesystem

Contents

Install ROS
Managing Your Environment
Create a ROS Workspace

Install ROS

Before starting these tutorials please complete installation as described in the ROS installation instructions.

Note: If you installed ROS from a package manager like apt, then those packages will not be write accessible and should not be edited by you the user. When working with ROS packages from source or when creating a new ROS package, you should always work in a directory that you have access to, like your home folder.

Managing Your Environment

During the installation of ROS, you will see that you are prompted to source one of several setup.*sh files, or even add this 'sourcing' to your shell startup script. This is required because ROS relies on the notion of combining spaces using the shell environment. This makes developing against different versions of ROS or against different sets of packages easier.

If you are ever having problems finding or using your ROS packages make sure that you have your environment properly setup. A good way to check is to ensure that environment variables like ROS_ROOT and ROS_PACKAGE_PATH are set:

$ printenv | grep ROS

If they are not then you might need to 'source' some setup.*sh files.

Environment setup files are generated for you, but can come from different places:

ROS packages installed with package managers provide setup.*sh files
rosbuild workspaces provide setup.*sh files using tools like rosws
Setup.*sh files are created as a by-product of building or installing catkin packages

Note: Throughout the tutorials you will see references to rosbuild and catkin. These are the two available methods for organizing and building your ROS code. Generally, rosbuild is easy to use and simple, where as catkin uses more standard CMake conventions, so it is more sophisticated, but provides more flexibility especially for people wanting to integrate external code bases or who want to release their software. For a full break down visit catkin or rosbuild.

If you just installed ROS from apt on Ubuntu then you will have setup.*sh files in '/opt/ros/<distro>/', and you could source them like so:

$ source /opt/ros/<distro>/setup.bash

Using the short name of your ROS distribution instead of <distro>

If you installed ROS Kinetic, that would be:

$ source /opt/ros/kinetic/setup.bash

You will need to run this command on every new shell you open to have access to the ROS commands, unless you add this line to your .bashrc. This process allows you to install several ROS distributions (e.g. indigo and kinetic) on the same computer and switch between them.

On other platforms you will find these setup.*sh files wherever you installed ROS.

Create a ROS Workspace

These instructions are for ROS Groovy and later. For ROS Fuerte and earlier, select rosbuild.

Let's create and build a catkin workspace:

$ mkdir -p ~/catkin_ws/src
$ cd ~/catkin_ws/
$ catkin_make

The catkin_make command is a convenience tool for working with catkin workspaces. Running it the first time in your workspace, it will create a CMakeLists.txt link in your 'src' folder.

Python 3 users in ROS Melodic and earlier: note, if you are building ROS from source to achieve Python 3 compatibility, and have setup your system appropriately (ie: have the Python 3 versions of all the required ROS Python packages installed, such as catkin) the first catkin_make command in a clean catkin workspace must be:

$ catkin_make -DPYTHON_EXECUTABLE=/usr/bin/python3

This will configure catkin_make with Python 3. You may then proceed to use just catkin_make for subsequent builds.

Additionally, if you look in your current directory you should now have a 'build' and 'devel' folder. Inside the 'devel' folder you can see that there are now several setup.*sh files. Sourcing any of these files will overlay this workspace on top of your environment. To understand more about this see the general catkin documentation: catkin. Before continuing source your new setup.*sh file:

$ source devel/setup.bash

To make sure your workspace is properly overlayed by the setup script, make sure ROS_PACKAGE_PATH environment variable includes the directory you're in.

$ echo $ROS_PACKAGE_PATH
/home/youruser/catkin_ws/src:/opt/ros/kinetic/share

When working with ROS source code, it is often useful to do so in a "workspace". For the following ROS tutorials you will need an area for working on tutorials and creating new ROS stacks and packages.

rosws is a tool that provides a uniform interface to various version control systems such as SVN, Git and Mercurial and for managing all packages installed in a ROS overlay. An extensive tutorial on rosws can be found here.

Creating a new workspace

The following command creates a new workspace in ~/fuerte_workspace which extends the set of packages installed in /opt/ros/fuerte:

rosws init ~/fuerte_workspace /opt/ros/fuerte

Note: rosws is part of the rosinstall package, which is not installed by default. The following command downloads it using the Ubuntu package manager:

sudo apt-get install python-rosinstall

Creating a sandbox directory for new packages

New packages need to be put in a path that is in the variable ROS_PACKAGE_PATH. All directories that are managed by rosws, i.e. that have been added using rosws are automatically added to the ROS_PACKAGE_PATH when the file setup.bash of the corresponding workspace is sourced. Although new packages should always be put in repositories that have been installed using rosws, it can be very convenient to have a sandbox directory where for instance packages created during the tutorials can be put without requiring any additional rosws commands. For that we create a new directory sandbox and add it to the hidden .rosinstall file with rosws:

mkdir ~/fuerte_workspace/sandbox
rosws set ~/fuerte_workspace/sandbox

Every time the entries in the workspace change, it is necessary to re-source ~/fuerte_workspace/setup.bash to make sure that the updated ROS_PACKAGE_PATH is used.

source ~/fuerte_workspace/setup.bash

It is very common to replace the line source /opt/ros/fuerte/setup.bash to source the setup.bash in ~/fuerte_workspace or whichever workspace you use most often.

A more complete ROS Workspace tutorial can be found here.

Confirmation

To confirm that your package path has been set, echo the ROS_PACKAGE_PATH variable.

$ echo $ROS_PACKAGE_PATH

You should see something similar to:

/home/your_user_name/fuerte_workspace/sandbox:/opt/ros/fuerte/share:/opt/ros/fuerte/stacks

Now that your environment is setup, continue with the ROS file system tutorial.

ROS 2 Documentation

Wiki

Page

User